home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 014 / pc_more.arc / PC-MORE.DOC next >
Text File  |  1985-12-18  |  17KB  |  426 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.                                      PC-Write
  17.                                 by Donald L. Nash
  18.  
  19.                                   December, 1985
  20.                                    Version 1.2
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.                                                
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                               Section 1:  Introduction
  64.  
  65.       PC-More is a pager program similar to the UNIX* more program.  It is
  66.   designed to work on the IBM Personal Computer, PC XT, and PC AT, as well as
  67.   compatibles.  The purpose of PC-More is to display a file one screenful at a
  68.   time for easy viewing.  The PC-DOS "type" command can do this, but the text
  69.   scrolls too fast for most people to read.  Beginning with version 2.0, PC-DOS
  70.   supplied its own version of a more filter, but it is extremely limited in its
  71.   usefulness, since it can only display one screenful at a time.  People who are
  72.   used to the UNIX version of more expect to be able to move through the file in
  73.   any increment they choose, not just a screenful at a time.  PC-More corrects
  74.   this problem.
  75.  
  76.  
  77.                             Section 2:  Invoking PC-More
  78.  
  79.       PC-More can be used to read from a file or to read from a pipe.  To invoke
  80.   PC-More to read from a file, simple type the following in responce to the PC-
  81.   DOS prompt:
  82.  
  83.           A>more file1.ext [file2.ext ... ]
  84.  
  85.       The part in brackets is optional.  It simply means that you can type any
  86.   number of filenames after the word "more."  When PC-More reaches the end of one
  87.   file, it will automatically go on to the next one on the command line.  Moving
  88.   between files is explained below.
  89.  
  90.       If you want PC-More to read from a pipe, where it will read the output of
  91.   some other command as its input, then you would invoke it like this:
  92.  
  93.           A>command | more
  94.  
  95.   where "command" is some program or PC-DOS command which writes to the PC-DOS
  96.   stdout device (usually the console screen).  In either case, PC-More accepts
  97.   the same commands once it is invoked, with a few exceptions explained below.
  98.  
  99.       Constructs like this:
  100.  
  101.           A>command | more file1.ext [file2.ext ... ]
  102.  
  103.  
  104.       *UNIX is a trademark of ATT Bell Laboratories.
  105.  
  106.                                       - 1 -    
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.   should ALWAYS be avoided.  If you would expect PC-More to read from the pipe
  115.   first, then go on to the files, you would be wrong.  Under PC-DOS, there is no
  116.   way to tell directly if the stdin and stdout devices have been redirected
  117.   through a pipe.  PC-More simply assumes that if there are no filenames on the
  118.   command line, then it must be reading from a pipe.  This is somewhat risky, but
  119.   it is the only way to go when using PC-DOS.  The above construction will
  120.   confuse PC-More into thinking that stdin has not been redirected, producing
  121.   potentially hazardous results for some of the commands (explained in the next
  122.   section).
  123.  
  124.  
  125.                             Section 3:  PC-More Commands
  126.  
  127.   Part 1:  Motion Commands
  128.  
  129.       If you have used programs like PC-More before, then you should skip the
  130.   first four parts of this section, since they are something of a tutorial
  131.   description of the PC-More commands.  Part 5 has a summary of all the commands
  132.   which will probably be enough for you.
  133.  
  134.       Once PC-More has been invoked, it will clear the screen and display the
  135.   first screenful of data.  When the screen fills, the following message appears
  136.   on the bottom line of the screen:
  137.  
  138.   --filename.ext--
  139.  
  140.   where "filename.ext" is the name of the file from which PC-More is reading.  If
  141.   it is reading from a pipe, then "filename.ext" will be "stdin."  You may now
  142.   type any of the PC-More commands.
  143.  
  144.       To see the next screenful of data, simply type a space.  The screen will
  145.   clear and the next screenful will appear.  PC-More will clear the screen every
  146.   time it reaches the bottom with the following exceptions:
  147.  
  148.       1.  Advancing one line at a time will never clear the screen, even if it is
  149.           full.  This is a feature which allows you to display two lines which
  150.           may be on different (but consecutive) screens.
  151.  
  152.       2.  If the screen is not full when the prompt appears and command is given
  153.           which will fill the screen and cause scrolling, then PC-More will not
  154.           clear the screen when it fills.  An example of this would be the
  155.           following situation:  The screen is currently full.  The user types 'h'
  156.           to request the next half screen of data.  The screen is cleared and the
  157.           next half screen appears at the top of the screen.  The user then types
  158.  
  159.                                       - 2 -    
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.           a space to see the next full screen.  The text will scroll down until
  168.           it hits the bottom of the screen.  PC-More will not clear the screen to
  169.           display the rest of the data.  Instead, it will scroll up the text
  170.           already on the screen.
  171.  
  172.       Now that the issue of screen clearing is out of the way, the other two
  173.   motion commands can be described.  To advance only one line, hit the return
  174.   key.  The next line will appear and the prompt will reappear.  To advance half
  175.   a screen, which would be the next 12 lines, hit the 'h' key in responce to the
  176.   prompt.  The screen will be cleared if necessary and the next 12 lines will
  177.   appear, followed by the prompt.
  178.  
  179.       These three commands can be preceded by a numeric argument up to three
  180.   digits long.  This argument will tell the following motion command to repeat
  181.   itself the specified number of times.  Note that when the "advance one line"
  182.   command is given an argument, it will clear the screen when necessary.  As an
  183.   example of using arguments, the following command will show the next five
  184.   screenfuls of data without pausing or clearing the screen when given to the
  185.   prompt:
  186.  
  187.           5<sp>
  188.  
  189.   Here, <sp> means "hit the space bar."  Similarly, <cr> would mean "hit the
  190.   enter key."  Only the three motion commands will use the argument.  The other
  191.   commands will simply ignore the argument and clear it when they finish.
  192.  
  193.       The final motion command is 'r', for "rewind file."  This will reset the
  194.   read/write pointer to the beginning of the file.  This is handy if you
  195.   accidently pass up what you are looking for.  You can rewind the file and start
  196.   over at the beginning.  While this is not as handy as backward paging commands
  197.   would be, it is all that is available at the moment.  Backward paging commands
  198.   may come out in future versions of PC-More.  Important Note:  "rewind file"
  199.   will not work if you are reading from a pipe!  There is no way to tell PC-DOS
  200.   to rewind the pipe.
  201.  
  202.   Part 2:  File commands
  203.  
  204.       If you listed more than one filename on the command line which invoked PC-
  205.   More, then you can move between them with the 'n' "next file" and 'p' "previous
  206.   file" commands.  When PC-More reaches the end of a file, it pauses and prints
  207.   out the following prompt:
  208.  
  209.   --filename.ext [EOF]--
  210.  
  211.  
  212.                                       - 3 -    
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.   This means that there is no more data in the current file.  Any of the forward
  221.   motion commands described above will automatically move to the next file on the
  222.   command line.  You can go on to the next file at any time by simply typing 'n'
  223.   in responce to the prompt.  The current file is closed and the next file is
  224.   opened.  If you are on the last file (or if you are reading from a pipe), then
  225.   typing 'n' will cause PC-More to exit, since there is no next file.
  226.  
  227.       If you wish to go to the previous file on the command line, then simply
  228.   type a 'p'.  The current file is closed and the previous file is opened.  If
  229.   you are reading from the first file on the command line (or from a pipe), then
  230.   'p' will have no effect other than printing a message on the last line which
  231.   says that you are already on the first file.
  232.  
  233.       If you wish to read from some file that is not listed on the command line,
  234.   type 'f'.  The prompt is replaced with the message:
  235.  
  236.   New file:
  237.  
  238.   You may now type the name of the file you wish to read from.  If you make a
  239.   typo, use the backspace key to fix it.  If you try to backspace over the
  240.   prompt, then the command is aborted.  Likewise, if you type a control-G at any
  241.   time while entering the new filename, the command will be aborted.  Control-G
  242.   can be used at any time to erase either the numeric argument or any text
  243.   arguments that some of the commands prompt for.
  244.  
  245.       You may use "open new file" at any time, even when you are reading from a
  246.   pipe.  The rest of the pipe is ignored.  However, you will not be able to edit
  247.   the new file or push to an inferior command interpreter.  These commands and
  248.   their restrictions are explained below in Part 3 of this section.
  249.  
  250.   Part 3:  Running Other Programs Under PC-More
  251.  
  252.       If you wish to execute a PC-DOS command, run a program, or load in inferior
  253.   command interpreter, then use the '!' "push to DOS" command.  '!' may be
  254.   followed by an optional command which PC-DOS is to execute.  This command may
  255.   an internal PC-DOS command or a program on disk.  If the '!' is not followed
  256.   by any text, then the DOS command interpreter is loaded.  When a DOS command
  257.   finishes, or when a program exits, or when you type "exit" to the inferior
  258.   shell, control returns to PC-More and the last screen of data is redisplayed.
  259.  
  260.       This command will NOT work properly when reading from a pipe.  If you try
  261.   to push to an inferior shell, PC-More will prevent this from happening.  If
  262.   you try to execute a PC-DOS command or run a program, you are asked to confirm
  263.   that you really want to do this.  To confirm, type 'y'.  These precautions are
  264.  
  265.                                       - 4 -    
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.   necessary.  If you were to push to an inferior shell or any program which
  274.   reads from the DOS stdin device, then the lines of data from the pipe will be
  275.   executed as if PC-DOS was reading from a batch file.  This is because stdin
  276.   has been redirected, so any calls to it go to the pipe.  Because of this
  277.   misfeature of PC-DOS, PC-More tries to protect you from disaster.  Note that
  278.   when you are reading from a pipe and you use the 'f' "open new file" command,
  279.   stdin is still redirected and this command is still disabled.
  280.  
  281.       WARNING:  If you invoke PC-More from a pipe and with arguments on the
  282.   command line as you were warned not to do in Section 2, then strange things
  283.   will happen if you try to use '!'.  PC-More will not know that stdin has been
  284.   redirected and will blindly let you push to an inferior shell.  You will then
  285.   find out first hand what happens.  No harm is done, but you must reboot you PC
  286.   to stop the process.  Since a file is open when this happens, you may loose
  287.   data.
  288.  
  289.       As a special case of the above command, you can call up an editor on the
  290.   current file by typing 'e', for "edit current file."  The name of the editor
  291.   to use is obtained by translating the environment variable EDITOR.  If EDITOR
  292.   is not set, then the PC-DOS line editor "edlin" is used.  To set the environ-
  293.   ment variable EDITOR, type the following to PC-DOS before invoking PC-More:
  294.  
  295.           A>set editor=whatever.exe
  296.  
  297.   The word "editor" does not need to be capitalized.  However, there must be no
  298.   spaces to the left of the = sign.  Spaces are significant and will be part of
  299.   the variable name.  PC-More will NOT recognize the following:
  300.  
  301.           A>set editor = whatever.exe
  302.  
  303.   If you type something like this, you will get "edlin" when you type 'e'.
  304.  
  305.       If you are reading from a pipe, then 'e' is disabled, even if you use the
  306.   'f' command to switch to a real file.  This is done as a precaution.  If your
  307.   editor uses PC-DOS function calls to read from stdin, then you are in the same
  308.   trouble as you would be in if you pushed to an inferior shell.  You editor
  309.   would begin reading from the pipe.  The same warning about invoking PC-More
  310.   from a pipe and with arguments applies here as well.
  311.  
  312.   Part 4:  Other commands
  313.  
  314.       If you forget what the PC-More commands are, type '?', which is the help
  315.   command.  It will print a summary of the commands known to PC-More.
  316.  
  317.  
  318.                                       - 5 -    
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.       Typing a 'v' will print the version number of your copy of PC-More.
  327.  
  328.       If you are entering a numeric argument for the motion commands or a text
  329.   argument for the '!' or 'f' commands, then you can cancel the argument by
  330.   typing control-G.  This will also abort the '!' and 'f' commands and return
  331.   you to the PC-More command level.
  332.  
  333.       Of course, there is a quit command for PC-More as well.  Type 'q' and you
  334.   will be returned to the process which called PC-More (usually PC-DOS).
  335.  
  336.   Part 5:  Command Summary
  337.  
  338.       Here is a summary of all PC-More commands.  If you have used programs like
  339.   PC-More before (which most of you probably have), then this is probably all
  340.   you will need to be able to use PC-More:
  341.  
  342.           <sp>    next screen
  343.           <cr>    next line
  344.           h       next half screen
  345.           r       rewind the current file
  346.           e       edit the current file
  347.           n       go to the next file
  348.           p       go to the previous file
  349.           f       open a new file
  350.           !       push do DOS
  351.           ^G      clear argument or abort '!' or 'f'
  352.           ?       help
  353.           v       print the version number
  354.           q       quit to DOS
  355.  
  356.  
  357.                  Section 4:  Source Notes and Portability Concerns
  358.  
  359.       PC-More is written in Computer Innovations C86 version 2.20G.  The code is
  360.   pretty straight-forward and heavily commented.  It should not be very hard to
  361.   determine what a piece of code does.
  362.  
  363.       I made extensive use of external variables in PC-More.  There are 8
  364.   external variables in the program.  This is necessary because they are used by
  365.   several functions.  Some of the external variables are used by only two
  366.   functions, but one function does not always call the other one directly.
  367.   Instead, funtion a() and funtion c() may both use a variable, but a() does not
  368.   call c().  Rather, a() calls b() which then calls c().  This isn't the best
  369.   style of programming, but PC-More is small and not very complicated.  Besides,
  370.  
  371.                                       - 6 -    
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.   all external variables start with the characters "x_", to they are easy to
  380.   spot.
  381.  
  382.       There are only three functions used in PC-More which may not be supplied
  383.   with other C compilers.  These are:
  384.  
  385.       key_getc()  This function reads a character directly from the keyboard
  386.                   rather than from stdin.  It returns an int with the ASCII
  387.                   code of the character typed in the lower byte and the scan
  388.                   code of the key struck in the upper byte.  In PC-More, the
  389.                   scan code is masked off to zero.  This function will wait
  390.                   for a key to be struck and the return key is not needed to
  391.                   make it return.
  392.  
  393.       crt_cls()   This function is used to clear the screen and home the cursor.
  394.  
  395.       crt_mode()  The crt_cls() function has a bug in it.  When it clears the
  396.                   screen, the forground color (the color in which the characters
  397.                   are printed), is set to zero.  The call crt_mode(7) corrects
  398.                   this bug.  You probably don't need to use this function.
  399.  
  400.                   If you don't want to clear the screen each time, or you don't
  401.                   have a function to clear the screen, simply eliminate all
  402.                   calls to crt_cls() and crt_mode().  You should also eliminate
  403.                   all references to the variable npl in the main() routine.
  404.  
  405.   All the other functions I used in PC-More are available in the standard UNIX
  406.   C libraries under 4.2 BSD.  If your compiler does not come with some of these
  407.   functions, look them up in section 3 of the UNIX manual to find out what they
  408.   do.
  409.  
  410.  
  411.                               Section 5:  Conclusion
  412.  
  413.   As a final note to add to the end of this manual, I'd like to say that PC-More
  414.   is a public domain program.  You can copy it, modify it chop it up, whatever
  415.   you want to do, but please don't sell it.  I welcome any comments, bug fixes,
  416.   new features (searches and backward paging would be nice), etc.  My e-mail
  417.   address is:
  418.  
  419.       UUCP:   ...!{ihnp4 | allegra | seismo!ut-sally}!ut-ngp!dlnash
  420.  
  421.       ARPA:   dlnash@ngp.UTEXAS.EDU
  422.  
  423.  
  424.                                       - 7 -    
  425.  
  426.